home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc / Developer Documentation / Recipes, Tech Notes & Articles / Tech Notes / Utilities Documentation / SEUtils < prev    next >
Encoding:
Text File  |  1996-07-16  |  4.2 KB  |  87 lines  |  [TEXT/ttxt]
  1. OpenDoc™ Utilities Documentation
  2.  
  3.  
  4. Semantic Events Utilities
  5.  
  6. © 1993-1996  Apple Computer, Inc. All Rights Reserved.
  7. Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
  8. Mac and OpenDoc are trademarks of Apple Computer, Inc. 
  9.  
  10. Introduction
  11.  
  12. This C++ class implements utility functions useful in code dealing with Semantic Events (a.k.a. Apple Events.)
  13.  
  14. Routines (SEUtils.cpp)
  15.  
  16. ODBoolean MissingParams(const AppleEvent* message);
  17.  
  18. Checks for the presence of a parameters that haven't yet been retrieved from the Apple event. Uses the method of getting the attribute keyMissedKeywordAttr.
  19.  
  20. OSErr DecodeOrdinal(AEDesc ordData, long count, long* index,
  21.                     Boolean* allFlag, Boolean* zeroFlag);
  22.  
  23. This routine was lifted from the sample code for the app Scriptable Text Editor. Here's the description from the source file.
  24.  
  25.  This routine is used whenever an element is specified by an absolute position
  26.   within a sequence of elements - such as "word 3 of window 'johnson'", "any line
  27.   of item 17 of window 'Kelvin'", etc.  The data specifying the position can be
  28.   a positive integer (which just means the actual position of the element in the
  29.   sequence: 1 for the first element, 2 for the second, etc.), a negative integer
  30.   (which indicates position relative to the last element of the sequence: -1 is
  31.   the last element, -2 the next to last, etc.), or a descriptor of typeAbsoluteOrdinal:
  32.   kAEFirst, kAELast, kAEMiddle, kAEAny, or kAEAll.  
  33.   
  34.   DecodeOrdinal takes the data specifying the position, and a count of all the elements
  35.   in the sequence under consideration, and returns (whenever possible) a positive integer
  36.   (in the return VAR index) representing the actual position of the element in the sequence 
  37.   (1 for first, 2 for second, etc.).  It also returns flags indicating (a) whether the 
  38.   ordinal was kAEAll and (b) whether the count was 0; both of these are conditions that 
  39.   many calling routines will have to special-case.  In the case of kAEAll, the return VAR 
  40.   index is set to the count; in the case of count = 0, the return VAR index is set to 0.
  41.   
  42.   There are a few error conditions:  (a) count < 0; (b) bad ordData (not an integer, and
  43.   not one of the five defined absolute ordinal specifiers).  **CHECK - should "integer ordData
  44.   out of range" (for example, an integer > count, or < -count, or = 0) be an error,
  45.   or should we allow that so that people can talk about "the hypothetical element
  46.   beyond the last", or whatever?  For now, let's make that a non-error.
  47.   
  48.   INPUTS:    ordData        a descriptor that specifies an ordinal - either
  49.                           an integer (positive or negative) or something
  50.                         of typeAbsoluteOrdinal
  51.             count        the total number of elements in the group involved
  52.                         (number of windows, number or chars, or whatever)
  53.             index        return VAR for the actual position being described
  54.             allFlag        return VAR: TRUE if the ordData was kAEAll, FALSE o.w.
  55.             zeroFlag    return VAR: TRUE if the count was zero (for many
  56.                         calling routines this is an error condition), FALSE o.w.
  57.   OUTPUTS:    error code (noErr if none)
  58.  
  59. ODSLong GetSLongAttr(AppleEvent* ae, AEKeyword keyword);
  60.  
  61. Retrieves a signed long attribute from an Apple event.
  62.  
  63. ODSLong GetSLongAttrOD(ODAppleEvent* ae, AEKeyword keyword);
  64.  
  65. Retrieves a signed long attribute from an ODAppleEvent.
  66.  
  67. void ThrowIfCantCoerce( AEDesc* data, DescType desiredType ) ;
  68.  
  69. Performs an in-place coercion of the AEDesc and calls THROW on any error returned from AECoerceDesc. 
  70.  
  71. void ThrowIfNotAbsent( OSErr err ) ;
  72.  
  73. THROWS err if err is not equal to noErr or errAEDescNotFound.
  74.  
  75. ODSLong CountEmbeddedParts(Environment* ev, ODPart* prt);
  76.  
  77. Uses the embedded frames iterator to count the number of embedded parts. If the prt is the shell, 1 is returned.
  78.  
  79. void UpdateUserToken(Environment* ev, ODNameResolver* resolver,
  80.                         ODOSLToken* odToken, AEDesc* desc);
  81.  
  82. Updates the user token in odToken with data in desc. desc is disposed.
  83.  
  84. OSErr ODDisposeAppleEvent( AppleEvent* aevt );
  85.  
  86. Call this to dispose an AppleEvent that was created by copying (e.g., using ODDescToAEDesc). Does a double-dispose of the AppleEvent. (If the AppleEvent is a copy of a send-to-self event, the AppleEvent cannot be disposed with a single call to AEDisposeDesc.)
  87.